home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / programm / GNU_C++ / LIB / NKCC-293.LZH / DOC / NKCC.TXT < prev   
Encoding:
Text File  |  1995-11-09  |  28.6 KB  |  719 lines
  1.  
  2. Documentation of: package\source\nkcc.s
  3. Date of creation: Thursday  09.11.1995  16.14
  4.  
  5. ********************************************************************************
  6. *
  7. *  Project name : NORMALIZED KEY CODE CONVERTER (NKCC)
  8. *  Module name  : Main module
  9. *  Symbol prefix: nkc
  10. *
  11. *  Author       : Harald Siegmund (HS)
  12. *  Co-Authors   : -
  13. *  Write access : HS
  14. *
  15. *  Notes        : The symbol NKCGEM will have to be defined on the assembler's
  16. *                 command line when translating the source of NKCC. Set its
  17. *                 value to 1 if you like to create the complete version. A value
  18. *                 of 0 will supress inclusion of the GEM part, making NKCC a few
  19. *                 KBytes smaller. Some functions and the GEM parameter arrays
  20. *                 are not available then.
  21. *
  22. *                 Translate this source with the Pure assembler:
  23. *                 pasm [-B] -DNKCGEM=1 -Onkcc.o nkcc.s
  24. *                 pasm [-B] -DNKCGEM=0 -Onkcc_tos.o nkcc.s
  25. *
  26. *                 WARNING: Old versions of the Pure assemblers have serious
  27. *                          bugs! Version Jun 21 1993 works fine.
  28. *
  29. *-------------------------------------------------------------------------------
  30.  
  31.  
  32. ****************************************************************************
  33. *                         ASSEMBLER CONTROL SECTION                        *
  34. ****************************************************************************
  35.  
  36. *KEY &NKCGEM
  37. *     define this symbol on the assembler's command line
  38. *     =0    create TOS-version of NKCC (without GEM part)
  39. *     =1    create GEM-version of NKCC
  40.  
  41.                .include "nkcc.i"             ; NKCC definitions
  42.  
  43.  
  44. ****************************************************************************
  45. *                                  EXPORT                                  *
  46. ****************************************************************************
  47.  
  48.                                              ; functions
  49.                .globl   nkc_init             ; init NKCC
  50.                .globl   nkc_exit             ; exit NKCC
  51.                .globl   nkc_set              ; set special key flags
  52.                .globl   nkc_conin            ; NKCC key input via GEMDOS
  53.                .globl   nkc_cstat            ; console input status via GEMDOS
  54.                .globl   nkc_tconv            ; TOS key code converter
  55.                .globl   nkc_gconv            ; GEM key code converter
  56.                .globl   nkc_n2tos            ; NKC to TOS key code converter
  57.                .globl   nkc_n2gem            ; NKC to GEM key code converter
  58.                .globl   nkc_kstate           ; return shift key state
  59.                .globl   nkc_timer            ; return 200 Hz system clock
  60.                .globl   nkc_cmp              ; compare two key codes
  61.                .globl   nkc_vlink            ; link function to XBRA vector list
  62.                .globl   nkc_vunlink          ; unlink function from XBRA list
  63.                .globl   nkc_toupper          ; convert character to upper case
  64.                .globl   nkc_tolower          ; convert character to lower case
  65.  
  66.                .if      NKCGEM=1
  67.  
  68.                 .globl  nkc_multi            ; NKCC multi event handler
  69.                 .globl  nkc_amulti           ; multi event, assembler binding
  70.                 .globl  nkc_contrl           ; GEM parameter arrays
  71.                 .globl  nkc_intin
  72.                 .globl  nkc_intout
  73.                 .globl  nkc_adrin
  74.                 .globl  nkc_adrout
  75.                 .globl  nkc_ptsin
  76.                 .globl  nkc_ptsout
  77.  
  78.                .endif   ; .if NKCGEM=1
  79.  
  80.  
  81. ****************************************************************************
  82. *                            GLOBAL TEXT SECTION                           *
  83. ****************************************************************************
  84.  
  85.  
  86. ****************************************************************************
  87. *
  88. *  nkc_init: initialize NKCC
  89. *  # G U
  90. *
  91. *  C prototype: int nkc_init(unsigned long flags,int vdihnd,int *pglobal);
  92. *---------------------------------------------------------------------------
  93. *  This function initializes NKCC. It must be called once before any other
  94. *  NKCC routine. It performs some tasks that may be important for you to
  95. *  know:
  96. *
  97. *  - bit 3 of the system variable <conterm> ($484.B) is set
  98. *  - a 200 Hz clock interrupt is installed, using the XBRA method (ID is
  99. *    "NKCC")
  100. *
  101. *  nkc_init() gets some flags which configure NKCC and enable some special
  102. *  functions:
  103. *
  104. *  NKI?_BUTHND       install NKCC's button event handler (see documentation
  105. *                    NKCC.DOC for details)
  106. *  NKI?_BHTOS        additional flag: install only, if TOS has mouse click bug
  107. *  NKI?_NO200HZ      don't install the 200 Hz timer interrupt
  108. *
  109. *  Notes:
  110. *
  111. *  - if NKCC is assembled as TOS-only version (symbol NKCGEM set to 0),
  112. *    both NKI?_BUTHND and NKI?_BHTOS flags are ignored.
  113. *
  114. *  - if the button event handler is installed, the NKI?_NO200HZ flag is
  115. *    ignored (because the 200 Hz clock is needed by the handler). Besides,
  116. *    the initialization continues:
  117. *
  118. *    - an own GEM trap handler (trap #2) is installed, using the XBRA method
  119. *      (to be up to date when a new double click time is set via the AES
  120. *      function evnt_dclick())
  121. *
  122. *    - a vex_butv() call (VDI) is made to install a mouse button exchange
  123. *      handler
  124. *
  125. *  In:   D0.L           miscellaneous flags (NKI?_...); see above
  126. *        D1.W           handle of an open VDI workstation
  127. *                       (must only be valid if the button handler is
  128. *                       installed)
  129. *        A0.L           ^applications GLOBAL array (from GEM parameter block)
  130. *                       not used in the TOS version of NKCC
  131. *
  132. *  Out:  D0.W           NKCC's version number as 4 digit BCD
  133. *                       (main # in high byte, sub # in low byte)
  134. *
  135. *  Reg:  D:01234567   A:01234567   CCR
  136. *          U**.....     **......    *
  137. *
  138. ****************************************************************************
  139.  
  140.  
  141. ****************************************************************************
  142. *
  143. *  nkc_exit: exit NKCC
  144. *  # G U
  145. *
  146. *  C prototype: int nkc_exit(void);
  147. *---------------------------------------------------------------------------
  148. *  nkc_exit() must be called before the program is quit. It removes all
  149. *  handlers installed in the system.
  150. *
  151. *  In:   -
  152. *
  153. *  Out:  D0.W           status flag:
  154. *                       0     OK
  155. *                       -1    can't remove 200 Hz clock interrupt
  156. *                       -2    can't remove trap #2 handler
  157. *                       -3    can't remove both handlers
  158. *                       An error can happen if somebody corrupted the
  159. *                       XBRA vector list. This is fatal!
  160. *
  161. *  Reg:  D:01234567   A:01234567   CCR
  162. *          ***.....     **......   =D0.W
  163. *
  164. ****************************************************************************
  165.  
  166.  
  167. ****************************************************************************
  168. *
  169. *  nkc_set: set special key flags
  170. *  # G
  171. *
  172. *  C prototype: void nkc_set(unsigned long flags);
  173. *---------------------------------------------------------------------------
  174. *  This function is used to enable/disable special key handling procedures.
  175. *  The features which can be set are:
  176. *
  177. *  - direct input of ASCII codes; when switched on, pressing the Alternate
  178. *    key plus one of the numbers on the numeric keypad will start the input
  179. *    of a decimal ASCII number. The input is finished either when 3 digits
  180. *    are typed in or the Alternate key is released. NKCC will return the
  181. *    corresponding character with the entered ASCII code. This feature makes
  182. *    it possible to use the whole range of the character set (from 0 ... 255).
  183. *
  184. *  - deadkey management; when switched on, NKCC will combine some combi-
  185. *    nations of two key strokes to one character. This is used to generate
  186. *    characters with accents which are not on the keyboard. The supported
  187. *    deadkeys are:
  188. *
  189. *    ^   +   aeiou      =  âêîôû       (NKS?_D_CIRCUM)
  190. *    ~   +   nNaoAo     =  ñÑãõÃÕ      (NKS?_D_TILDE)
  191. *    '   +   eEaiou     =  éÉáíóú      (NKS?_D_AGUI)
  192. *    `   +   aeiouA     =  àèìòùÀ      (NKS?_D_GRAVE)
  193. *    ¨   +   aeiouyAOU  =  äëïöüÿÄÖÜ   (NKS?_D_UMLAUT)
  194. *    "   +   aeiouyAOU  =  äëïöüÿÄÖÜ   (NKS?_D_QUOTE)
  195. *    °   +   aA         =  åÅ          (NKS?_D_SMOERE)
  196. *    ,   +   cC         =  çÇ          (NKS?_D_CEDIL)
  197. *    /   +   oO24       =  øؽ¼        (NKS?_D_SLASH)
  198. *
  199. *    The quote character as synonym for umlaut is e.g. needed on the Dutch
  200. *    keyboard, where neither umlaut characters nor the umlaut itself are
  201. *    available.
  202. *
  203. *    Each deadkey can be enabled/disabled separately.
  204. *
  205. *  - Control key emulation: Control plus an ASCII code in the range of
  206. *    $40...$5F (characters @, A...Z, [, \, ], ^ and _) is converted
  207. *    to an ASCII code of $00...$1F.
  208. *
  209. *
  210. *  In:   D0.L           new key flags (bit set = feature on):
  211. *                       NKS?_ALTNUM       ASCII input
  212. *                       NKS?_D_...        deadkey ...
  213. *                                         (NKSf_DEADKEY: all deadkeys)
  214. *                       NKS?_CTRL         control key emulation
  215. *
  216. *  Out:  -
  217. *
  218. *  Reg:  D:01234567   A:01234567   CCR
  219. *          ***.....     **......    *
  220. *
  221. ****************************************************************************
  222.  
  223.  
  224. ****************************************************************************
  225. *
  226. *  nkc_conin: raw console character input
  227. *  # G
  228. *
  229. *  C prototype: int nkc_conin(void);
  230. *---------------------------------------------------------------------------
  231. *  This routine replaces the Gemdos function Crawcin. However, it returns
  232. *  a WORD with the key code in normalized format rather than a LONG with
  233. *  the key code in the language dependend TOS format.
  234. *
  235. *  In:   -
  236. *
  237. *  Out:  D0.W           key code in normalized format
  238. *                       for details see nkc_tconv()
  239. *        CCR            set according content of D0.W
  240. *
  241. *  Reg:  D:01234567   A:01234567   CCR
  242. *          W**.....     **......   =D0.W
  243. *
  244. ****************************************************************************
  245.  
  246.  
  247. ****************************************************************************
  248. *
  249. *  nkc_cstat: return console character input status
  250. *  # G
  251. *
  252. *  C prototype: int nkc_cstat(void);
  253. *---------------------------------------------------------------------------
  254. *  This function checks, if a key is in the key input buffer or not.
  255. *
  256. *  In:   -
  257. *
  258. *  Out:  D0.W           flag:
  259. *                       0     no key in buffer
  260. *                       -1    at least one key in buffer
  261. *        CCR            set according content of D0.W
  262. *
  263. *  Reg:  D:01234567   A:01234567   CCR
  264. *          W**.....     **......   =D0.W
  265. *
  266. ****************************************************************************
  267.  
  268.  
  269. ****************************************************************************
  270. *
  271. *  nkc_multi: NKCC multi event
  272. *  # G U
  273. *
  274. *  C prototype: int cdecl nkc_multi(
  275. *                  int mflags,
  276. *                  int mbclicks,int mbmask,int mbstate,
  277. *                  int mm1flags,int mm1x,int mm1y,int mm1width,int mm1height,
  278. *                  int mm2flags,int mm2x,int mm2y,int mm2width,int mm2height,
  279. *                  int *mmgpbuff,
  280. *                  int mtlocount,int mthicount,
  281. *                  int *mmox,int *mmoy,int *mmbutton,int *mmokstate,
  282. *                  int *mkreturn,int *mbreturn);
  283. *---------------------------------------------------------------------------
  284. *  nkc_multi() is a binding function to the AES multi event handler. The
  285. *  only differences are the keyboard events and the shift key state: the key
  286. *  codes are returned in normalized format (see nkc_tconv()), the shift key
  287. *  state is compatible to the NKF?_... flags. For a detailed description of
  288. *  the whole mass of parameters consult your AES manual or compiler handbook!
  289. *
  290. *  In:    4(SP).w       event mask (MU_...)
  291. *         6(SP).w       MU_BUTTON: max # of clicks to wait for
  292. *         8(SP).w       MU_BUTTON: mask of buttons to check
  293. *        10(SP).w       MU_BUTTON: button states to wait for
  294. *        12(SP).w       MU_M1: area enter/leave flag
  295. *        14(SP).w       MU_M1: x position of area
  296. *        16(SP).w       MU_M1: y position of area
  297. *        18(SP).w       MU_M1: width of area
  298. *        20(SP).w       MU_M1: height of area
  299. *        22(SP).w       MU_M2: area enter/leave flag
  300. *        24(SP).w       MU_M2: x position of area
  301. *        26(SP).w       MU_M2: y position of area
  302. *        28(SP).w       MU_M2: width of area
  303. *        30(SP).w       MU_M2: height of area
  304. *        32(SP).L       MU_MESAG: ^8 words of message buffer
  305. *        36(SP).w       MU_TIMER: low word of time to wait
  306. *        38(SP).w       MU_TIMER: high word of time to wait
  307. *        40(SP).L       MU_BUTTON/M1/M2: ^word for mouse x
  308. *        44(SP).L       MU_BUTTON/M1/M2: ^word for mouse y
  309. *        48(SP).L       MU_BUTTON/M1/M2: ^word for button state
  310. *        52(SP).L       MU_BUTTON/M1/M2: ^word for shift state
  311. *        56(SP).L       MU_KEYBD: ^word for key code in normalized format
  312. *        60(SP).L       MU_BUTTON: ^word for # of mouse clicks
  313. *
  314. *  Out:  D0.W           mask of occured events (MU_...)
  315. *
  316. *  Reg:  D:01234567   A:01234567   CCR
  317. *          W**.....     **......    *
  318. *
  319. ****************************************************************************
  320.  
  321.  
  322. ****************************************************************************
  323. *
  324. *  nkc_amulti: NKCC multi event called by Assembler  *** added by Gerd Knops
  325. *  # G U
  326. *
  327. *  See description of nkc_multi()!
  328. *
  329. *  usage: instead of    move.l   #aespb,d1
  330. *                       move  #$c8,d0
  331. *                       trap  #2
  332. *
  333. *         do            jsr   nkc_amulti
  334. *
  335. *  In:   all parameters for evnt_multi in the AES parameter arrays
  336. *
  337. *  Out:  values in intout and message buffer
  338. *
  339. *  Reg:  D:01234567   A:01234567   CCR
  340. *          ***.....     **......    *
  341. *
  342. ****************************************************************************
  343.  
  344.  
  345. ****************************************************************************
  346. *
  347. *  nkc_tconv: TOS key code converter
  348. *  # G R
  349. *
  350. *  C prototype: int nkc_tconv(long toskey);
  351. *---------------------------------------------------------------------------
  352. *  This is the most important function within NKCC: it takes a key code
  353. *  returned by TOS and converts it to the sophisticated normalized format.
  354. *
  355. *  Note: the raw converter does no deadkey handling, ASCII input or
  356. *        Control key emulation.
  357. *
  358. *  In:   D0.L           key code in TOS format:
  359. *                                   0                    1
  360. *                       bit 31:     ignored              ignored
  361. *                       bit 30:     ignored              ignored
  362. *                       bit 29:     ignored              ignored
  363. *                       bit 28:     no CapsLock          CapsLock
  364. *                       bit 27:     no Alternate         Alternate pressed
  365. *                       bit 26:     no Control           Control pressed
  366. *                       bit 25:     no left Shift key    left Shift pressed
  367. *                       bit 24:     no right Shift key   right Shift pressed
  368. *
  369. *                       bits 23...16: scan code
  370. *                       bits 15...08: ignored
  371. *                       bits 07...00: ASCII code (or rubbish in most cases
  372. *                          when Control or Alternate is pressed ...)
  373. *
  374. *  Out:  D0.W           normalized key code:
  375. *                       bits 15...08: flags:
  376. *                                   0                    1
  377. *                       NKF?_FUNC   printable char       "function key"
  378. *                       NKF?_RESVD  ignore it            ignore it
  379. *                       NKF?_NUM    main keypad          numeric keypad
  380. *                       NKF?_CAPS   no CapsLock          CapsLock
  381. *                       NKF?_ALT    no Alternate         Alternate pressed
  382. *                       NKF?_CTRL   no Control           Control pressed
  383. *                       NKF?_LSH    no left Shift key    left Shift pressed
  384. *                       NKF?_RSH    no right Shift key   right Shift pressed
  385. *
  386. *                       bits 07...00: key code
  387. *                       function (NKF?_FUNC set):
  388. *                          < 32: special key (NK_...)
  389. *                          >=32: printable char + Control and/or Alternate
  390. *                       no function (NKF?_FUNC not set):
  391. *                          printable character (0...255!!!)
  392. *
  393. *        CCR            set according content of D0.W
  394. *
  395. *  Reg:  D:01234567   A:01234567   CCR
  396. *          U**.....     **......   =D0.W
  397. *
  398. ****************************************************************************
  399.  
  400.  
  401. ****************************************************************************
  402. *
  403. *  nkc_gconv: GEM key code converter
  404. *  # G R
  405. *
  406. *  C prototype: int nkc_gconv(int gemkey);
  407. *---------------------------------------------------------------------------
  408. *  Why a second key code converter, you ask? Well, in some cases it might
  409. *  happen that the key status byte of the original key code (with states
  410. *  of both Shift keys, Control, Alternate and CapsLock) is lost. Then
  411. *  this converter function must be called, which uses another algorithm
  412. *  to construct the normalized key code.
  413. *
  414. *  Notes:
  415. *  -  the raw converter does no deadkey handling, ASCII input or Control
  416. *     key emulation.
  417. *  -  NKCC does not use this function at all for its own purposes!
  418. *  -  some key combinations cannot be distinguished without the flag byte!
  419. *     For example, "Alternate A" and "Shift Alternate A" produce the same
  420. *     result. Whenever possible, use nkc_tconv()!
  421. *
  422. *  In:   D0.W           key code in GEM format:
  423. *                       bits 15...08: scan code
  424. *                       bits 07...00: ASCII code
  425. *
  426. *  Out:  D0.W           normalized key code (see nkc_tconv() for details)
  427. *        CCR            set according content of D0.W
  428. *
  429. *  Reg:  D:01234567   A:01234567   CCR
  430. *          U**.....     **......   =D0.W
  431. *
  432. ****************************************************************************
  433.  
  434.  
  435. ****************************************************************************
  436. *
  437. *  nkc_n2tos: convert normalized key codes back to TOS format
  438. *  # G R
  439. *
  440. *  C prototype: long nkc_n2tos(int nkcode);
  441. *---------------------------------------------------------------------------
  442. *  In some cases you might have to have key codes in the original TOS format
  443. *  again, as returned by the GEMDOS functions Cconin(), Crawcin() or the BIOS
  444. *  function Bconin(). Use nkc_n2tos() to convert them. For a detailed
  445. *  description of the returned format consult the header of the function
  446. *  nkc_tconv().
  447. *
  448. *  In:   D0.W           key code in normalized format
  449. *
  450. *  Out:  D0.L           key code in TOS format:
  451. *                       bits 24...31: shift key flags
  452. *                       bits 23...16: scan code
  453. *                       bits 08...15: reserved (0)
  454. *                       bits 00...07: ASCII code
  455. *        CCR            set according content of D0.L
  456. *
  457. *  Reg:  D:01234567   A:01234567   CCR
  458. *          U**.....     **......   =D0.L
  459. *
  460. ****************************************************************************
  461.  
  462.  
  463. ****************************************************************************
  464. *
  465. *  nkc_n2gem: convert normalized key codes back to GEM format
  466. *  # G R
  467. *
  468. *  C prototype: int nkc_n2gem(int nkcode);
  469. *---------------------------------------------------------------------------
  470. *  Similar to nkc_n2tos(), this function converts normalized key codes back
  471. *  to the operating system's format. The result is a key code as returned
  472. *  by the AES functions evnt_keybd() respectively evnt_multi().
  473. *
  474. *  In:   D0.W           key code in normalized format
  475. *
  476. *  Out:  D0.W           key code in GEM format:
  477. *                       bits 08...15: scan code
  478. *                       bits 00...07: ASCII code
  479. *        CCR            set according content of D0.W
  480. *
  481. *  Reg:  D:01234567   A:01234567   CCR
  482. *          U**.....     **......   =D0.W
  483. *
  484. ****************************************************************************
  485.  
  486.  
  487. ****************************************************************************
  488. *
  489. *  nkc_kstate: return state of Shift/Control/Alternate/CapsLock in
  490. *              normalized format
  491. *  # G R
  492. *
  493. *  C prototype: int nkc_kstate(void);
  494. *---------------------------------------------------------------------------
  495. *  This is a very *FAST* function which returns the state of the Shift/
  496. *  Control/Alternate and CapsLock keys in normalized format.
  497. *
  498. *  In:   -
  499. *
  500. *  Out:  D0.W           normalized key flags:
  501. *                                   0                    1
  502. *                       NKF?_CAPS   no CapsLock          CapsLock
  503. *                       NKF?_ALT    no Alternate         Alternate pressed
  504. *                       NKF?_CTRL   no Control           Control pressed
  505. *                       NKF?_LSH    no left Shift key    left Shift pressed
  506. *                       NKF?_RSH    no right Shift key   right Shift pressed
  507. *
  508. *        CCR            set according content of D0.W
  509. *
  510. *  Reg:  D:01234567   A:01234567   CCR
  511. *          w**.....     **......   =D0.W
  512. *
  513. ****************************************************************************
  514.  
  515.  
  516. ****************************************************************************
  517. *
  518. *  nkc_timer: return current value of 200 Hz system clock
  519. *  # G R
  520. *
  521. *  C prototype: unsigned long nkc_timer(void);
  522. *---------------------------------------------------------------------------
  523. *  This is a very *FAST* function which returns the content of the 200 Hz
  524. *  system clock.
  525. *
  526. *  In:   -
  527. *
  528. *  Out:  D0.L           current 200 HZ system clock value
  529. *
  530. *  Reg:  D:01234567   A:01234567   CCR
  531. *          w**.....     **......    *
  532. *
  533. ****************************************************************************
  534.  
  535.  
  536. ****************************************************************************
  537. *
  538. *  nkc_cmp: compare two key codes
  539. *  # G R
  540. *
  541. *  C prototype: int nkc_cmp(int refkey,int kcode);
  542. *---------------------------------------------------------------------------
  543. *  nkc_cmp() compares key codes. What for, you ask? A simple "if key_code1
  544. *  = key_code2" would also do it? No! This function follows some specific
  545. *  rules, which improve the flexibility of key code comparism.
  546. *
  547. *  One of the key codes passed to nkc_cmp() is called the "reference key
  548. *  code". The other is the "test key code", which is got from nkc_conin()
  549. *  or nkc_multi(). Some flags of the reference code are treated a special
  550. *  way:
  551. *
  552. *  NKF?_IGNUM (same as NKF?_RESVD)
  553. *     if set, the numeric keypad flag doesn't matter
  554. *
  555. *  NKF?_CAPS (CapsLock)
  556. *     if set, the case of the ASCII code doesn't matter
  557. *
  558. *  NKFf_SHIFT (both Shift key flags)
  559. *     if BOTH shift flags are set, the combination of shift key flags in
  560. *     the test key code doesn't matter: only one shift flag has to be set,
  561. *     no matter which one.
  562. *
  563. *  In:   D0.W           reference key code
  564. *        D1.W           key code to test
  565. *
  566. *  Out:  D0.W           flag: 1 = key codes match
  567. *                             0 = key codes don't match
  568. *        CCR            set according content of D0.W
  569. *
  570. *  Reg:  D:01234567   A:01234567   CCR
  571. *          u**.....     **......   =D0.W
  572. *
  573. ****************************************************************************
  574.  
  575.  
  576. ****************************************************************************
  577. *
  578. *  nkc_vlink: link function to XBRA vector list
  579. *  # G U
  580. *
  581. *  C prototype: void nkc_vlink(long vector,int mode,void *pfnc);
  582. *---------------------------------------------------------------------------
  583. *  This function can be used to change system vectors and let them point
  584. *  to own functions, using a standard method. The vector, which should be
  585. *  changed, is described by the contents of D0.L and D1.W. It can be
  586. *  either a standard vector number, e.g. 2 for the bus error exception
  587. *  vector, or the absolute address of the vector, e.g. $502 for the screen
  588. *  dump vector. The function to install must have the following header:
  589. *
  590. *  .dc.b    "XBRA"         magic longword
  591. *  .dc.b    "myID"         four ASCII character ID of the function
  592. *                          (NKCC uses "NKCC", for example)
  593. *  .dc.l    0              buffer for the old vector content
  594. *  function: ...           start of the function code
  595. *
  596. *  The function should end with:
  597. *
  598. *  move.l   function-4(pc),-(sp)
  599. *  rts
  600. *
  601. *
  602. *  Note: in NKXM_ADR mode, this function automatically switches (temporary)
  603. *        to Supervisor mode to prevent bus errors
  604. *
  605. *
  606. *  In:   D0.L           vector descriptor
  607. *        D1.W           mode:
  608. *                       NKXM_NUM = D0.L contains a vector number
  609. *                       NKXM_ADR = D0.L contains a vector address
  610. *        A0.L           ^function to install (NOT ^XBRA header!)
  611. *
  612. *  Out:  -4(A0.L).L     old content of vector
  613. *
  614. *  Reg:  D:01234567   A:01234567   CCR
  615. *          ***.....     **......    *
  616. *
  617. ****************************************************************************
  618.  
  619.  
  620. ****************************************************************************
  621. *
  622. *  nkc_vunlink: unlink function from XBRA vector list
  623. *  # G U
  624. *
  625. *  C prototype: int nkc_vunlink(long vector,int mode,void *pfnc);
  626. *---------------------------------------------------------------------------
  627. *  nkc_vunlink() removes a function which was installed using the XBRA method.
  628. *  For details see nkc_link(). If the XBRA list was corrupted, the function
  629. *  aborts with an error code. This happens, when a non-XBRA routine is
  630. *  installed on the same vector after the nkc_vlink() call of the function
  631. *  to remove.
  632. *
  633. *  Note: the function automatically switches (temporary) to Supervisor mode
  634. *        to prevent bus errors
  635. *
  636. *  In:   D0.L           vector descriptor
  637. *        D1.W           mode:
  638. *                       NKXM_NUM = D0.L contains a vector number
  639. *                       NKXM_ADR = D0.L contains a vector address
  640. *        A0.L           ^function to remove (NOT ^XBRA header!)
  641. *
  642. *  Out:  D0.W           status:
  643. *                       0 = OK
  644. *                       -1 = can't remove (XBRA list corrupted)
  645. *        CCR            set according content of D0.W
  646. *
  647. *  Reg:  D:01234567   A:01234567   CCR
  648. *          U**.....     **......   =D0.W
  649. *
  650. ****************************************************************************
  651.  
  652.  
  653. ****************************************************************************
  654. *
  655. *  nkc_toupper: convert character to upper case
  656. *  # G
  657. *
  658. *  C prototype: unsigned char nkc_toupper(unsigned char chr);
  659. *---------------------------------------------------------------------------
  660. *  A character is converted to upper case. Examples:
  661. *
  662. *  'a'   ->   'A'          (converted)
  663. *  '/'   ->   '/'          (unchanged; there's no upper case version for this)
  664. *  'A'   ->   'A'          (unchanged; already converted)
  665. *
  666. *
  667. *  In:   D0.B           any character
  668. *
  669. *  Out:  D0.B           character converted to upper case
  670. *
  671. *  Reg:  D:01234567   A:01234567   CCR
  672. *          U**.....     **......    *
  673. *
  674. ****************************************************************************
  675.  
  676.  
  677. ****************************************************************************
  678. *
  679. *  nkc_tolower: convert character to lower case
  680. *  # G
  681. *
  682. *  C prototype: unsigned char nkc_tolower(unsigned char chr);
  683. *---------------------------------------------------------------------------
  684. *  The counterpart of nkc_toupper(). A character is converted to lower case.
  685. *
  686. *  In:   D0.B           any character
  687. *
  688. *  Out:  D0.B           character converted to lower case
  689. *
  690. *  Reg:  D:01234567   A:01234567   CCR
  691. *          U**.....     **......    *
  692. *
  693. ****************************************************************************
  694.  
  695.  
  696. ****************************************************************************
  697. *                            GLOBAL BSS SECTION                            *
  698. ****************************************************************************
  699.  
  700.  
  701. *  GEM parameter arrays
  702. *  (needed if using nkc_amulti())
  703.  
  704.                .if      NKCGEM=1
  705.  
  706. nkc_contrl:     .ds.w   32                   ; control array
  707. nkc_intin:      .ds.w   32                   ; integer input array
  708. nkc_intout:     .ds.w   32                   ; integer output array
  709. nkc_adrin:      .ds.l   32                   ; address input array
  710. nkc_adrout:     .ds.l   32                   ; address output array
  711. nkc_ptsin:      .ds.l   32                   ; pointers input array
  712. nkc_ptsout:     .ds.l   32                   ; pointers output array
  713.  
  714.                .endif   ; .if NKCGEM=1
  715.  
  716.  
  717. * End Of File
  718.  
  719.